安装

​ 运行下面指令后会在$GOPATH/bin中生成一个apidoc的可执行程序

1
2
3
4
5
6
7
8
9
10
11
cd $GOPATH/src/github.com/caixw/

git clone https://github.com/caixw/apidoc.git

cd $GOPATH/src/github.com/caixw/apidoc

git checkout v3.0

go build

cp apidoc $GOPATH/bin/

生成流程

  1. 在项目工程目录下生成apidoc配置文件：
1
apidoc -g
  1. 在代码中每个API接口处理函数前加一些特殊的注释，注释格式见下文
  2. 注释完后运行apidoc ，即在当前目录的doc目录生成相应项目的文档
  3. 打开相应的html即可阅读

注释格式

​ 在写代码时，需要在代码中加上特定格式的注释，以便用apidoc生成文档。

  • 项目文档的描述：在项目的某一个源文件（推荐main.go）的开头加上该项目文档的注释
1
2
3
4
5
6
7
/**
 * @apidoc <title of doc>
 * @apiVersion <version>
 * @apiBaseURL <domain>
 * @apiContent
 * 描述，可以多行，支持html
 */

​ <title of doc>填写为文档的名称

​ <version>为文档的版本

​ <domain>问API的域名，比如https://test.com

​ 例子：

1
2
3
4
5
6
7
/**
 * @apidoc USER模块API接口
 * @apiVersion V0.1
 * @apiBaseURL https://www.wukoon-app.com
 * @apiContent
 * 描述，可以多行，支持html
 */
  • API的描述：在需要导出的API相应处理函数前加上特定的注释
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/*
 * @api <method> <url> <summary>
 * @apiGroup <group>
 * @apiQuery <QueryName> <type> <summary>
 
 * @apiRequest json
 * @apiHeader <key> <summary>
 * @apiParam <ParamName> <type> <summary>
 * @apiExample json
 * <body data example in json format>
 
 * @apiSuccess <status> <summary>
 * @apiParam <ParamName> <type> <summary>
 * @apiExample json
 * <Success data in json format>
 
 * @apiError <status> <summary>
 * @apiParam <ParamName> <type> <summary>
 * @apiExample json
 * <fail data in json format>
 */

​ <method>是API的HTTP method，比如GET

​ <url>是API的路径，比如/api/v1/user/user

​ <summary>是简要说明

​ <group>对 api 的分组信息，不同的分组，最终可能会被呈现在不同的页面。

​ <QueryName>Query的名称

​ <type> Query的类型，比如int，string等

​ <key>HTTP请求头字段，有需要指定的话可以使用

​ <ParamName> 请求参数名称

​ <body data example in json format>请求body的例子

​ <status>HTTP状态码，比如200

​ <Success data in json format>成功返回数据例子

​ <fail data in json format>错误返回数据例子

​ 例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/**
 * @api PUT /api/v1/user/user 修改用户profile
 * @apiGroup user
 * @apiQuery userid int 执行修改请求的用户id
 * @apiQuery token string 执行修改请求的用户token
 
 * @apiRequest json
 * @apiHeader session 12345
 * @apiParam userid int 要修改的用户id
 * @apiParam name string 将用户id对应的名称修改为name
 * @apiExample json
 * {"userid":1,"name":"wubo"}
 
 * @apiSuccess 200 OK
 * @apiParam errcode int 错误代码
 * @apiParam errmsg string 错误信息
 * @apiExample json
 * {"errcode":0,"errmsg":"ok"}
 
 * @apiError 200 OK
 * @apiParam errcode int 错误代码
 * @apiParam errmsg string 错误信息
 * @apiExample json
 * {"errcode":30002,"errmsg":"invalid parameter"}
 */

参考

apidoc项目：https://github.com/caixw/apidoc

apidoc文档：http://apidoc.tools/